OpenEuphoria

save_map

include map.e 
namespace map 
public function save_map(map the_map_, object file_name_p, integer type_ = SM_TEXT) 

saves a map to a file.

Parameters:

1. m : a map.
2. file_name_p : Either a sequence, the name of the file to save to, or an open file handle as returned by open().
3. type : an integer. SM_TEXT for a human-readable format (default), SM_RAW for a smaller and faster format, but not human-readable.

Returns:

An integer, the number of keys saved to the file, or -1 if the save failed.

Comments:

If file_name_p is an already opened file handle, this routine will write to that file and not close it. Otherwise, the named file will be created and closed by this routine.

The SM_TEXT type saves the map keys and values in a text format which can be read and edited by standard text editor. Each entry in the map is saved as a KEY/VALUE pair in the form

key = value 

Note that if the 'key' value is a normal string value, it can be enclosed in double quotes. If it is not thus quoted, the first character of the key determines its Euphoria value type. A dash or digit implies an atom, an left-brace implies a sequence, an alphabetic character implies a text string that extends to the next equal '=' symbol, and anything else is ignored.

Note that if a line contains a double-dash, then all text from the double-dash to the end of the line will be ignored. This is so you can optionally add comments to the saved map. Also, any blank lines are ignored too.

All text after the '=' symbol is assumed to be the map item's value data.

Because some map data can be rather long, it is possible to split the text into multiple lines, which will be considered by load_map as a single logical line. If an line ends with a comma (,) or a dollar sign ($), then the next actual line is appended to the end of it. After all these physical lines have been joined into one logical line, all combinations of `",$"` and `,$` are removed.

For example:

one = {"first", 
"second", 
"third", 
$ 
} 
second = "A long text ",$ 
"line that has been",$ 
" split into three lines" 
third = {"first", 
"second", 
"third"} 

is equivalent to

one = {"first","second","third"} 
second = "A long text line that has been split into three lines" 
third = {"first","second","third"} 

The SM_RAW type saves the map in an efficient manner. It is generally smaller than the text format and is faster to process, but it is not human readable and standard text editors can not be used to edit it. In this format, the file will contain three serialized sequences:

1. Header sequence: {integer:format version, string: date and time of save (YYMMDDhhmmss), sequence: euphoria version {major, minor, revision, patch}}
2. Keys. A list of all the keys
3. Values. A list of the corresponding values for the keys.

Example 1:

include std/error.e 
 
map AppOptions 
if save_map(AppOptions, "c:\myapp\options.txt") = -1 
    crash("Failed to save application options") 
end if 
 
if save_map(AppOptions, "c:\myapp\options.dat", SM_RAW) = -1 
    crash("Failed to save application options") 
end if 

See Also:

load_map